TagBlog Theme
=============

This is the repository of the [Pico CMS][p] tagblog theme.
It is fully centered around a tag list/cloud - other means of navigation, apart from a manually built menu, have not been taken onto account.

It is a minimal theme - no javascript, no 3rd-party resources, simple CSS design without animations or rounded corners etc.

It's also a responsive theme, a.k.a. mobile friendly.

Colors can be customised. Two example CSS are included.

It is - was - based on the [NotePaper][np] theme, but has been largely rewritten to focus on the one aspect that was most important to me. I believe that tagblog runs lighter than the original NotePaper.  
Both the original NotePaper and TagBlog are licensed GPL3.

It also includes a modified version of the [mcb_TableOfContent][mcbtoc] plugin, which comes with its own separate MIT License. I hope that was the correct thing to do.

Screenshots
----------

[![tagblog screenshot][sst]][ss]

[Dark theme][ssd]; [Mobile][ssm]

Links
-----

TagBlog can be found in two locations:

<https://notabug.org/ohnonot/tagblog>  
<https://framagit.org/ohnonot/tagblog>


Install
-------

- Change to your Pico installation's themes directory:

        $ cd <your pico install>/themes

- Clone this repository:

        $ git clone https://<notabug or framagit>.org/ohnonot/tagblog
  You can also download the .zip, but make sure extracting it does not create another folder level.  
  In the end you should have this README.md and all twig templates in
  `<your pico install>/themes/tagblog/`.

- Symlink the `TableofContents` plugin (it's inside the `res` folder) to the `plugins` folder:

        $ cd <your pico install>/plugins && ln -s ../themes/tagblog/res/TableOfContents
  Alternatively you can also copy the folder:

        $ cd <your pico install>/plugins && cp -r ../themes/tagblog/res/TableOfContents .

- The folder `tagblog/content-base` contains important files without which tagblog cannot function (and also an example article that can be deleted). Copy them into your `content` folder.

- Copy `res/tagblog.yml` to your Pico CMS installation's `config` folder:

        $ cd <your pico install>/config && cp ../themes/tagblog/res/tagblog.yml .

- Add the following line to your `config/config.yml`:

        theme: tagblog

Usage
-----

The theme is fully centered around tags.

Make sure your markdown articles include a valid `tags:` (case insensitive) line in their YAML headers.
A valid header might look like this:

    ---
    Title: Load bash builtin from file
    Date: 27.02.2018
    Tags: linux,bash
    Template: post
    ---

Tags are separated by commas.
An article that doesn't have a `Tags:` line (or commented out like `#Tags:`) will not show up in the tag cloud/list, not in search results and not in the list of all posts.
It can still be accessed with its direct page URL.

My blog posts all use the `post` template, and are all thrown in one big folder. They can be grouped in subfolders, but the tagblog theme has no way of representing that (the page URL will represent that though).

Configuration
-------------

    <your pico install>/config/tagblog.yml

is fairly straightforward and self-explanatory.

`colors:` you can create your own color schemes by copying one of the existing `color-*.css` files inside `<your pico install>/themes/tagblog/css` to something named `color-custom-<yourtheme>.css` and editing that.
You need to define it as `colors: custom-<yourtheme>` (and not just `<yourtheme>`) in tabglog.yml.
This naming convention ensures that the git project remains untouched and you can easily `git pull` if there are updates.

`taglist` and `tagcloud` are different designs to show the same clickable lists of tags.

The `TableOfContent` options are explained in [mcb_TableOfContent][mcbtoc]'s original README.md, except for the last one (`template`).

You can also add a feed on your site. To do that, in the `feed` dict, set `enabled` to `true`. If you wish that feed entries contains your entire post and not only the first lines, set `content` to true.

Disclaimers
-----------

You should be familiar with the concepts of PicoCMS.

For deeper understanding I recommend to get familiar with [Twig templating][tt].

Please open an issue in any of the two repositories if you think you found something that should be fixed.

---

Greetings,  
<https://notabug.org/ohnonot>  
<https://framagit.org/ohnonot>

[p]: https://github.com/picocms/Pico
[ss]: https://dt.iki.fi/stuff/blog/tagblog/TagBlog.png
[sst]: https://dt.iki.fi/stuff/blog/tagblog/thumb_TagBlog.png
[ssd]: https://dt.iki.fi/stuff/blog/tagblog/TagBlog-2.png
[ssm]: https://dt.iki.fi/stuff/blog/tagblog/TagBlog-mobile-1.png
[mcbtoc]: https://github.com/mcbSolutions/Pico-Plugins/tree/master/mcb_TableOfContent
[tt]: https://twig.symfony.com/doc/3.x/
[np]: https://github.com/mayamcdougall/NotePaper
